/*
 * Copyright (c) 2010 Google Inc.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package com.google.api.data.contacts.v3;

import com.google.api.client.googleapis.GoogleUrl;
import com.google.api.client.util.DateTime;
import com.google.api.client.util.Key;

/**
 * URL for contacts API.<br>
 * It contains a list of all the URL parameters for the feed.
 * 
 * @author Nicolas Garnier
 */
public class ContactsUrl extends GoogleUrl {

  /** Valid values for the sortOrder attribute */
  public static enum SortOrder {
    ascending, descending;
  }

  /** Valid values for the orderBy attribute */
  public static enum OrderBy {
    lastmodified;
  }

  /**
   * The maximum number of entries to return. If you want to receive all of the
   * contacts, rather than only the default maximum, you can specify a very
   * large number for max-results.
   */
  @Key("max-results")
  public Integer maxResults;

  /** The 1-based index of the first result to be retrieved (for paging). */
  @Key("start-index")
  public Integer startIndex;

  /** The inclusive lower bound on entry update dates. */
  @Key("updated-min")
  public DateTime updatedMin;

  /** Sorting criterion. */
  @Key("orderby")
  public OrderBy orderBy;

  /** Sorting order direction. */
  @Key("sortorder")
  public SortOrder sortOrder;

  /**
   * Include deleted contacts in the returned contacts feed. Deleted contacts
   * are shown as entries that contain nothing but an <atom:id> element and a
   * <gd:deleted> element. (Google usually retains placeholders for deleted
   * contacts for 30 days after deletion; during that time, you can request the
   * placeholders using the showdeleted query parameter.) Valid values are true
   * or false. When the server decides it cannot guarantee that it still has
   * information about all deleted contacts pertinent to the query, then it's
   * behavior depends on the value of the requirealldeleted query parameter.
   */
  @Key("showdeleted")
  public Boolean showDeleted;

  /**
   * Only relevant if showdeleted and updated-min are also provided. It dictates
   * the behavior of the server in case it detects that placeholders of some
   * entries deleted since the point in time specified as updated-min may have
   * been lost. If requirealldeleted is false, the server simply returns all the
   * placeholders it still knows about. If true, the server returns the 410 HTTP
   * response code. The default value is false.
   */
  @Key("requirealldeleted")
  public Boolean requireAllDeleted;

  /**
   * Constrains the results to only the contacts belonging to the group
   * specified. Value of this parameter specifies group ID.
   */
  @Key("group")
  public String group;

  /**
   * Constructs a new ContactsUrl with the given URL.
   * 
   * @param url
   */
  public ContactsUrl(String url) {
    super(url);
  }
}
